BigDFT.Atoms module

This module defines the atom class, which is a class which contains very general descriptions of a single atom.

AU_to_A = 0.52917721092

Conversion between Atomic Units and Bohr

MULTIPOLE_ANALYSIS_KEYS = ['q0', 'q1', 'q2', 'sigma', 'multipole character']

A list of valid keys for describing a multipole.

number_to_symbol(number)

Returns the symbol of atoms with a given atomic number.

Parameters:

number (int) – the atomic number to lookup.

Returns:

the atomic symbol with the given number.

Return type:

(str)

Warning

In case of Isotopes (eg. D), only the original symbol is returned.

class Atom(*args, **kwargs)

Defines a wrapper for atoms.

An atom may have many quantities associated with it. These quantities are get and set in a dictionary like fashion, allowing an atom to dynamically hold whatever data you need. However, we still wrap it in a class so that we can have some common operations for it, as well as so we can maintain suitable units.

It is this class’s responsibility to extract the main properties of an atom (position, symbol) from the dictionary.

Parameters:

data (dict) – A dictionary of miscellaneous values to associate with this atom.

property atomic_number

The atomic number of this atom.

property atomic_weight

The atomic number of this atom.

dict()

Convert to a dictionary.

get_external_potential(units='bohr')

Transform the atom into a dictionary ready to be put as external potential.

serialize(units='bohr')

Transform the atom in a dictionary that can be employed for the construction of dataframes or pandas series.

Parameters:

units (str) – the units for the positions

Returns:

the serialized dictionary

Return type:

dict

property is_link

Whether or not this atom is a link atom or not.

property is_ghost

Whether or not this atom is a ghost atom or not.

property nel

The number of electrons in this atom.

property q0

Provides the charge of the atom.

property q1

Provides the dipole of the atom.

set_multipole(mp, correct_charge=True)

Given another atom or a dictionary, this sets the multipole related values of this with those values.

Todo

Arrive at a standard that avoids having to do the charge correction here.

Parameters:

• mp (dict) – a dictionary which contains information about multipoles.

• correct_charge (bool) – currently there is an inconsistency in terms of gross charge, and this corrects it.

get_force()

Returns the force on the atom in the desired units.

Returns:

An array of position values.

set_force(force)

Given an atom or a dictionary, this sets the force.

Parameters:

force (list) – a list of force values.

property sym

Return the symbol for this atom

Returns:

the symbol for this atom

Return type:

(str)

get_position(units='bohr', cell=None)

Returns the position of the atom in the desired units.

Parameters:

• units (str) – the units to return the position in. Default is bohr.

• cell (BigDFT.UnitsCell.UnitCell) – the unit cell. If passed, the minimum image convention is enforced.

Returns:

An array of position values.

set_position(new_pos, units='bohr')

Set the position of the atom.

Parameters:

• new_pos (list) – a list of floats defining the new position.

• units (str) – the units of the new position being passed. Default is bohr.

get_ig_occupation(charge=None)

Retrieve the dictionary of the input guess occupation.

This method provides the specification to be passed to the ~func:BigDFT.InputActions.set_atomic_occupancy method.

Parameters:

charge (float) – value of the charge to be passed if the atom has to be ionized. If absent the value of q0 is taken instead.

Returns:

dictionary of the occupation for the atom.

Return type:

dict

IsReduced(units)

Checks if a string or atom has reduced as its units.

Parameters:

units (BigDFT.Atoms.Atom, str) – either a string or a Atom.

IsAngstroem(units)

Checks if a string or atom has angstroem as its units.

Parameters:

units – either a string or a (BigDFT.Atoms.Atom).

IsBohr(units)

Checks if a string or atom has bohr as its units.

Parameters:

units – either a string or a (BigDFT.Atoms.Atom).

_example()

The following is an example of module usage:

"""Test the atom module"""
safe_print("Access the full data")
test_atom = Atom({'r': [1.0, 0.0, 0.0], 'sym': "He", 'units': 'bohr'})
safe_print(dict(test_atom))
# Access the derived data
safe_print(test_atom.sym)
safe_print(test_atom.get_position())
safe_print(test_atom.get_position('angstroem'))
safe_print()

safe_print("Create a new atom with different units")
new_atom = Atom({
    'r': [float(x) for x in test_atom.get_position('angstroem')],
    'sym': test_atom.sym, 'units': 'angstroem'})
safe_print("Are these atoms equal?")
safe_print(new_atom == test_atom)
safe_print()

safe_print("Now other times we get an array that looks more like this")
test_atom = Atom(He=[1.0, 0.0, 0.0], units='bohr')
safe_print(dict(test_atom))
safe_print("But everything else works as expected")
safe_print(test_atom.sym)
safe_print(test_atom.get_position())
safe_print(new_atom == test_atom)
safe_print()

safe_print("The atom can be used as a dict for adding new properties.")
test_atom["frag"] = "ANA"
for key, value in test_atom.items():
    safe_print(key, value)
safe_print()
safe_print("And if we update the dictionary position or symbol,")
safe_print("everything else reacts with suitable caution.")
test_atom["He"] = [-1.0, 0.0, 0.0]
safe_print(dict(test_atom))
safe_print(test_atom.get_position('angstroem'))

safe_print("But you can change the symbol if you are working with the")
safe_print("other representation.")
safe_print(dict(new_atom))
new_atom["sym"] = "Na"
safe_print(new_atom.sym)
safe_print(dict(new_atom))
safe_print()

safe_print("One final check of the atom comparison")
new_atom["units"] = "bohr"
new_atom["r"] = [-1.0, 0.0, 0.0]
safe_print(new_atom.sym, new_atom.get_position())
safe_print(test_atom.sym, test_atom.get_position())
safe_print(new_atom == test_atom)
safe_print()

safe_print("We can also update the position")
safe_print(test_atom.get_position())
safe_print(dict(test_atom))
test_atom.set_position([1.0, 1.0, 1.0], units="angstroem")
safe_print(test_atom.get_position(units="angstroem"))
safe_print(dict(test_atom))
safe_print()